home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / text / misc / tr.lha / Tr / tr.man < prev   
Text File  |  1995-01-18  |  8KB  |  196 lines
  1.  
  2. ======================= BEGIN MAN PAGE ==========================
  3.  
  4. NAME
  5.        tr - translate or delete characters
  6.  
  7. SYNOPSIS
  8.        tr   [-cst]  [--complement]  [--squeeze-repeats]  [--trun-
  9.        cate-set1] string1 string2
  10.        tr {-s,--squeeze-repeats} [-c] [--complement] string1
  11.        tr {-d,--delete} [-c] string1
  12.        tr {-d,--delete}  {-s,--squeeze-repeats}  [-c]  [--comple-
  13.        ment] string1 string2
  14.  
  15.        GNU tr also accepts the --help and --version options.
  16.  
  17. DESCRIPTION
  18.        This  manual  page  documents  the  GNU version of tr.  tr
  19.        copies the standard input to the standard output, perform-
  20.        ing one of the following operations:
  21.  
  22.               o  translate, and optionally squeeze repeated char-
  23.               acters in the result
  24.               o squeeze repeated characters
  25.               o delete characters
  26.               o delete characters, then squeeze repeated  charac-
  27.               ters from the result.
  28.  
  29.        The  string1  and  (if  given)  string2  arguments  define
  30.        ordered sets of characters, referred to below as set1  and
  31.        set2.   These sets are the characters of the input that tr
  32.        operates on.  The --complement (-c) option  replaces  set1
  33.        with its complement (all of the characters that are not in
  34.        set1).
  35.  
  36.    SPECIFYING SETS OF CHARACTERS
  37.        The format of the string1 and string2 arguments  resembles
  38.        the  format  of regular expressions; however, they are not
  39.        regular expressions, only lists of characters.  Most char-
  40.        acters  simply  represent themselves in these strings, but
  41.        the strings can contain the shorthands listed  below,  for
  42.        convenience.   Some of them can be used only in string1 or
  43.        string2, as noted below.
  44.  
  45.        Backslash escapes.  A backslash followed  by  a  character
  46.        not listed below causes an error message.
  47.  
  48.        \a     Control-G.
  49.        \b     Control-H.
  50.        \f     Control-L.
  51.        \n     Control-J.
  52.        \r     Control-M.
  53.        \t     Control-I.
  54.        \v     Control-K.
  55.        \ooo   The character with the value given by ooo, which is
  56.               1 to 3 octal digits.
  57.        \\     A backslash.
  58.  
  59.        Ranges.  The notation `m-n' expands to all of the  charac-
  60.        ters  from m through n, in ascending order.  m should col-
  61.        late before n; if it doesn't, an  error  results.   As  an
  62.        example,  `0-9' is the same as `0123456789'.  Although GNU
  63.        tr does not support the System V syntax that  uses  square
  64.        brackets to enclose ranges, translations specified in that
  65.        format will still work as long as the brackets in  string1
  66.        correspond to identical brackets in string2.
  67.  
  68.        Repeated  characters.   The  notation  `[c*n]'  in string2
  69.        expands to n copies of character c.  Thus, `[y*6]' is  the
  70.        same  as `yyyyyy'.  The notation `[c*]' in string2 expands
  71.        to as many copies of c as are needed to make set2 as  long
  72.        as  set1.   If  n  begins  with  a 0, it is interpreted in
  73.        octal, otherwise in decimal.
  74.  
  75.        Character classes.  The notation `[:class-name:]'  expands
  76.        to  all  of the characters in the (predefined) class named
  77.        class-name.  The characters expand in no particular order,
  78.        except  for  the `upper' and `lower' classes, which expand
  79.        in  ascending  order.   When   the   --delete   (-d)   and
  80.        --squeeze-repeats (-s) options are both given, any charac-
  81.        ter class can be used in  string2.   Otherwise,  only  the
  82.        character  classes  `lower'  and  `upper'  are accepted in
  83.        string2, and then  only  if  the  corresponding  character
  84.        class  (`upper' and `lower', respectively) is specified in
  85.        the same relative position in string1.  Doing this  speci-
  86.        fies case conversion.  The class names are given below; an
  87.        error results when an invalid class name is given.
  88.  
  89.        alnum  Letters and digits.
  90.        alpha  Letters.
  91.        blank  Horizontal whitespace.
  92.        cntrl  Control characters.
  93.        digit  Digits.
  94.        graph  Printable characters, not including space.
  95.        lower  Lowercase letters.
  96.        print  Printable characters, including space.
  97.        punct  Punctuation characters.
  98.        space  Horizontal or vertical whitespace.
  99.        upper  Uppercase letters.
  100.        xdigit Hexadecimal digits.
  101.  
  102.        Equivalence classes.  The syntax `[=c=]' expands to all of
  103.        the  characters that are equivalent to c, in no particular
  104.        order.   Equivalence  classes  are  a   recent   invention
  105.        intended  to  support  non-English  alphabets.   But there
  106.        seems to be no standard way to define  them  or  determine
  107.        their contents.  Therefore, they are not fully implemented
  108.        in GNU tr; each  character's  equivalence  class  consists
  109.        only  of  that  character, which makes this a useless con-
  110.        struction currently.
  111.  
  112.    TRANSLATING
  113.        tr performs translation when string1 and string2 are  both
  114.        given  and  the  --delete  (-d)  option  is not given.  tr
  115.        translates each character of its input that is in set1  to
  116.        the  corresponding  character  in set2.  Characters not in
  117.        set1 are  passed  through  unchanged.   When  a  character
  118.        appears more than once in set1 and the corresponding char-
  119.        acters in set2 are not all the same, only the final one is
  120.        used.  For example, these two commands are equivalent:
  121.               tr aaa xyz
  122.               tr a z
  123.  
  124.        A  common  use of tr is to convert lowercase characters to
  125.        uppercase.  This can be done in many ways.  Here are three
  126.        of them:
  127.               tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  128.               tr a-z A-Z
  129.               tr '[:lower:]' '[:upper:]'
  130.  
  131.        When  tr  is  performing translation, set1 and set2 should
  132.        normally have the same length.  If set1  is  shorter  than
  133.        set2, the extra characters at the end of set2 are ignored.
  134.  
  135.        On the other hand, making set1 longer  than  set2  is  not
  136.        portable;  POSIX.2  says that the result is undefined.  In
  137.        this situation, the BSD tr pads set2 to the length of set1
  138.        by  repeating  the last character of set2 as many times as
  139.        necessary.  The System V tr truncates set1 to  the  length
  140.        of set2.
  141.  
  142.        By default, GNU tr handles this case like the BSD tr does.
  143.        When the --truncate-set1 (-t) option is given, GNU tr han-
  144.        dles  this case like the System V tr instead.  This option
  145.        is ignored for operations other than translation.
  146.  
  147.        Acting like the System  V  tr  in  this  case  breaks  the
  148.        relatively common BSD idiom:
  149.               tr -cs A-Za-z0-9 '\012'
  150.        because  it converts only zero bytes (the first element in
  151.        the  complement   of   set1),   rather   than   all   non-
  152.        alphanumerics, to newlines.
  153.  
  154.    SQUEEZING REPEATS AND DELETING
  155.        When  given  just the --delete (-d) option, tr removes any
  156.        input characters that are in set1.
  157.  
  158.        When given just  the  --squeeze-repeats  (-s)  option,  tr
  159.        replaces  each input sequence of a repeated character that
  160.        is in set1 with a single occurrence of that character.
  161.  
  162.        When given both the  --delete  and  the  --squeeze-repeats
  163.        options,  tr first performs any deletions using set1, then
  164.        squeezes repeats from any remaining characters using set2.
  165.  
  166.        The  --squeeze-repeats option may also be used when trans-
  167.        lating, in which case tr first performs translation,  then
  168.        squeezes repeats from any remaining characters using set2.
  169.  
  170.        Here are some examples to illustrate various  combinations
  171.        of options:
  172.  
  173.        Remove all zero bytes:
  174.               tr -d '\000'
  175.  
  176.        Put  all  words on lines by themselves.  This converts all
  177.        non-alphanumeric characters  to  newlines,  then  squeezes
  178.        each string of repeated newlines into a single newline:
  179.               tr -cs '[a-zA-Z0-9]' '[\n*]'
  180.  
  181.        Convert  each  sequence  of  repeated newlines to a single
  182.        newline:
  183.               tr -s '\n'
  184.  
  185.        GNU tr also accepts the following options in any  combina-
  186.        tion with the others.
  187.  
  188.        --help Print a usage message and exit with a non-zero sta-
  189.               tus.
  190.  
  191.        --version
  192.               Print version information on standard  output  then
  193.               exit.
  194.  
  195.        =================== END OF MAN PAGE ======================
  196.